QTML Compatibility

RESULTS

Returns NoErr (0) unless QuickTime is not installed on the target system or initialization fails.

DISCUSSION

Use InitializeQTML to initialize a QTML session, before calling EnterMovies . You should not make this call from a QuickTime component such as an image decompressor; it is provided only for host applications.

If you are writing a routine that does not know from context whether InitializeQTML has already been called, add a call to InitializeQTML at the beginning of the routine and a call to TerminateQTML at the end. It does no harm to call InitializeQTML more than once, as long as each call is nested with a matching call to TerminateQTML. If InitializeQTML has already been called, subsequent calls do nothing except increment a counter. Calls to TerminateQTML just decrement the counter (if it is nonzero). Only the first nested call to InitializeQTML and the last nested call to TerminateQTML do any actual work, so there is no penalty for having nested calls.

DISCUSSION

Use TerminateQTML to terminate a QTML session after calling ExitMovies . You should not make this call from a QuickTime component, such as an image decompressor; it is provided only for host applications.

DISCUSSION

The QTMLCreateMutex function creates a mutex object for guarded access to data structures and routines that require mutually exclusive access. In a multithreaded preemptive environment, such as Windows NT, you can use the various mutex utility functions such as QTMLGrabMutex to protect a shared resource from simultaneous access by multiple threads or processes. Mutex objects are used throughout QTML to provide such protection.

DISCUSSION

Call the QTMLDestroyMutex function to deallocate the mutex object created by QTMLCreateMutex .

DISCUSSION

Call the QTMLGrabMutex function when you require exclusive ownership of the resource guarded by the mutex. This function will return when you have gained this ownership. In the case where another thread or process holds the mutex, this function waits until that process or thread relinquishes control. If you need to determine if you can grab the mutex, without actually grabbing it, call QTMLTryGrabMutex .

DISCUSSION

Call the QTMLTryGrabMutex function when you need to preflight a QTMLGrabMutex call. It returns true if you are able to immediately grab the mutex, via the QTMLGrabMutex call, without having to wait. Under normal circumstances, you should not need to make this call.

DISCUSSION

Call the QTMLReturnMutex function to balance the call to QTMLGrabMutex when you are ready to relinquish control of the mutex and corresponding shared resource. By making this call you allow other processes or threads waiting for the release of this mutex to gain access.

DISCUSSION

Call the QTMLCreateSyncVar function to create a synchronization variable that allows for mutually-exclusive access to resources. The synchronization variable routines use atomic tests to ensure that the portions of the routines that perform the testing cannot be interrupted during the test.

DISCUSSION

Call the QTMLDestroySyncVar function to deallocate the QTMLSyncVar object created by QTMLCreateSyncVar .

DISCUSSION

Call the QTMLTestAndSetSyncVar function to perform a single test and set operation on the QTMLSyncVar object. The function returns 0 if you have acquired the lock.

DISCUSSION

Call the QTMLWaitAndSetSyncVar function to acquire the lock corresponding to a QTMLSyncVar object. This function will wait, yielding CPU time to other threads, until the lock is acquired.

DISCUSSION

Call the QTMLResetSyncVar function to relinquish the lock obtained from a previous call to QTMLWaitAndSetSyncVar .

DISCUSSION

The QTML function dispatcher includes a mechanism that prevents not only the Toolbox from getting reentered but also allows certain APIs to be callable at interrupt time. On the Macintosh, these calls are listed in Inside Macintosh, and require that the calling code not allocate, move, or purge memory. On Windows, threads that emulate interrupt handlers need to register with QTML, by calling the QTMLRegisterInterruptSafeThread function, so that API calls made from this thread are not blocked. You should make this call at the top of your thread main routine.

DISCUSSION

Use the QTMLRegisterInterruptSafeThread function to unregister an interrupt safe thread previously registered by the QTMLRegisterInterruptSafeThread function. You should make this call at the bottom of your thread main routine, just before the exit.

DISCUSSION

Use the QTMLYieldCPU function from within tight loops to yield time to other threads. Using this function is similar to calling SystemTask from within a Macintosh event loop.

DISCUSSION

Use the QTMLYieldCPUTime function from within tight loops to yield time to other threads. This function differs from QTMLYieldCPU in that you can specify the time to sleep as well as optionally have QTML process Win32 messages while waiting for the yield time to expire.

DISCUSSION

The QTMLSetWindowWndProc routine is useful if you want to perform some special Windows processing of the native messages that Windows sends to your WindowPtr .